<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Creating Streams</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
<link rel="up" href="../using_websocket.html" title="Using WebSocket">
<link rel="prev" href="../using_websocket.html" title="Using WebSocket">
<link rel="next" href="establishing_connections.html" title="Establishing Connections">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../using_websocket.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="establishing_connections.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.using_websocket.creating_streams"></a><a class="link" href="creating_streams.html" title="Creating Streams">Creating Streams</a>
</h3></div></div></div>
<p>
        The interface to the WebSocket implementation is a single template class
        <a class="link" href="../ref/boost__beast__websocket__stream.html" title="websocket::stream"><code class="computeroutput"><span class="identifier">stream</span></code></a>:
      </p>
<pre class="programlisting"><span class="comment">// A WebSocket stream</span>
<span class="keyword">template</span><span class="special">&lt;</span>
    <span class="keyword">class</span> <span class="identifier">NextLayer</span><span class="special">,</span>
    <span class="keyword">bool</span> <span class="identifier">deflateSupported</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">stream</span><span class="special">;</span>
</pre>
<p>
        An instance of the stream wraps an existing network transport object or other
        type of octet oriented stream. The wrapped object is called the "next
        layer" and must meet the requirements of <a class="link" href="../concepts/streams.html#beast.concepts.streams.SyncStream"><span class="bold"><strong>SyncStream</strong></span></a> if synchronous operations are performed,
        <a class="link" href="../concepts/streams.html#beast.concepts.streams.AsyncStream"><span class="bold"><strong>AsyncStream</strong></span></a>
        if asynchronous operations are performed, or both. Any arguments supplied
        to the constructor of the stream wrapper are forwarded to next layer's constructor.
      </p>
<p>
        The value of <code class="computeroutput"><span class="identifier">deflateSupported</span></code>
        determines if the stream will support (but not require) the permessage-deflate
        extension (<a href="https://tools.ietf.org/html/rfc7692" target="_top">rfc7692</a>)
        negotiation during handshaking. This extension allows messages to be optionally
        automatically compressed using the deflate algorithm prior to transmission.
        When this boolean value is <code class="computeroutput"><span class="keyword">false</span></code>,
        the extension is disabled. Applications which do not intend to use the permessage-deflate
        extension may set the value to <code class="computeroutput"><span class="keyword">false</span></code>
        to enjoy a reduction in the size of the compiled output, as the necessary
        compression code (included with Beast) will not be compiled in.
      </p>
<p>
        Here we declare a websocket stream over a TCP/IP socket with ownership of
        the socket. The <code class="computeroutput"><span class="identifier">io_context</span></code>
        argument is forwarded to the wrapped socket's constructor:
      </p>
<pre class="programlisting"><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;</span> <span class="identifier">ws</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">};</span>
</pre>
<h5>
<a name="beast.using_websocket.creating_streams.h0"></a>
        <span class="phrase"><a name="beast.using_websocket.creating_streams.using_ssl"></a></span><a class="link" href="creating_streams.html#beast.using_websocket.creating_streams.using_ssl">Using
        SSL</a>
      </h5>
<p>
        To use WebSockets over SSL, use an instance of the <a href="../../../../../../doc/html/boost_asio/reference/ssl__stream.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code></a>
        class template as the template type for the stream. The required <a href="../../../../../../doc/html/boost_asio/reference/io_context.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_context</span></code></a> and <a href="../../../../../../doc/html/boost_asio/reference/ssl__context.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span></code></a>
        arguments are forwarded to the wrapped stream's constructor:
      </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">beast</span><span class="special">/</span><span class="identifier">websocket</span><span class="special">/</span><span class="identifier">ssl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">asio</span><span class="special">/</span><span class="identifier">ssl</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span> <span class="identifier">ctx</span><span class="special">{</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">context</span><span class="special">::</span><span class="identifier">sslv23</span><span class="special">};</span>
<span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;&gt;</span> <span class="identifier">wss</span><span class="special">{</span><span class="identifier">ioc</span><span class="special">,</span> <span class="identifier">ctx</span><span class="special">};</span>
</pre>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
          Code which declares websocket stream objects using Asio SSL types must
          include the file <code class="literal">&lt;<a href="../../../../../../boost/beast/websocket/ssl.hpp" target="_top">boost/beast/websocket/ssl.hpp</a>&gt;</code>.
        </p></td></tr>
</table></div>
<h5>
<a name="beast.using_websocket.creating_streams.h1"></a>
        <span class="phrase"><a name="beast.using_websocket.creating_streams.non_owning_references"></a></span><a class="link" href="creating_streams.html#beast.using_websocket.creating_streams.non_owning_references">Non-owning
        References</a>
      </h5>
<p>
        If a socket type supports move construction, a websocket stream may be constructed
        around the already existing socket by invoking the move constructor signature:
      </p>
<pre class="programlisting"><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;</span> <span class="identifier">ws</span><span class="special">{</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sock</span><span class="special">)};</span>
</pre>
<p>
        Or, the wrapper can be constructed with a non-owning reference. In this case,
        the caller is responsible for managing the lifetime of the underlying socket
        being wrapped:
      </p>
<pre class="programlisting"><span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&amp;&gt;</span> <span class="identifier">ws</span><span class="special">{</span><span class="identifier">sock</span><span class="special">};</span>
</pre>
<p>
        Once the WebSocket stream wrapper is created, the wrapped object may be accessed
        by calling <a class="link" href="../ref/boost__beast__websocket__stream/next_layer/overload1.html" title="websocket::stream::next_layer (1 of 2 overloads)"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">next_layer</span></code></a>:
      </p>
<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">next_layer</span><span class="special">().</span><span class="identifier">shutdown</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">::</span><span class="identifier">shutdown_send</span><span class="special">);</span>
</pre>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
          Initiating operations on the next layer while websocket operations are
          being performed may result in undefined behavior.
        </p></td></tr>
</table></div>
<h5>
<a name="beast.using_websocket.creating_streams.h2"></a>
        <span class="phrase"><a name="beast.using_websocket.creating_streams.non_blocking_mode"></a></span><a class="link" href="creating_streams.html#beast.using_websocket.creating_streams.non_blocking_mode">Non-Blocking
        Mode</a>
      </h5>
<p>
        Please note that websocket streams do not support non-blocking modes.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2016, 2017 Vinnie Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../using_websocket.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="establishing_connections.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
